Selenium Python BDD Automation Framework

A comprehensive test automation framework built with Python, Selenium WebDriver, and Behave for BDD testing. The framework supports both UI and API testing using Behavior-Driven Development (BDD) with Gherkin syntax, including BrowserStack cloud testing integration.

🚀 Features

• BDD Framework - Complete Behavior-Driven Development with Behave
• Page Object Model (POM) - Clean, maintainable test structure
• Multi-browser Support - Chrome, Firefox, Safari with headless/headed modes
• BrowserStack Integration - Cloud testing on real devices and browsers
• API Testing - REST API testing with pytest-based tests
• Gherkin Syntax - Human-readable test scenarios
• Real API Integration - JSONPlaceholder API for testing
• Rich Reporting - Behave reports, Allure reports, and framework summaries
• Cross-platform - Windows, macOS, Linux support
• Test Coverage - Complete coverage of UI and API test cases
• Flexible Execution - Local and cloud testing options

⚡ Quick Start

Interactive Menu:

python quick_tests.py

Main Commands:

# Local UI tests
python run_tests.py --type ui --env local

# UI tests with Allure reporting
python run_tests.py --type ui --env local --allure

# BrowserStack UI tests  
python run_tests.py --type ui --env browserstack

# API tests
python run_tests.py --type api

# All tests
python run_tests.py --type all --env local

Allure Reporting:

# UI tests with Allure reports
python run_ui_tests_allure.py

# Using Makefile
make test-ui-allure

BrowserStack Setup:

# Set credentials
export BROWSERSTACK_ENABLED=true
export BROWSERSTACK_USERNAME=your_username
export BROWSERSTACK_ACCESS_KEY=your_access_key

# Run on BrowserStack
python run_tests.py --type ui --env browserstack --platform 0

📁 Project Structure

selenium-python-framework/
├── 🧪 Test Files
│   ├── run_tests.py          # Main test runner (UI + API)
│   ├── quick_tests.py        # Interactive test menu
│   ├── test_configs.py       # Test configurations
│   ├── features/             # BDD Feature Files (UI only)
│   │   ├── login.feature     # UI Login scenarios
│   │   ├── cart.feature      # UI Cart scenarios
│   │   ├── steps/            # Step Definitions
│   │   │   ├── login_steps.py    # UI Login step definitions
│   │   │   └── cart_steps.py     # UI Cart step definitions
│   │   ├── env.py            # Behave environment setup
│   │   └── behave.ini        # Behave configuration
│   └── api_tests/            # Pytest-based API Tests
│       ├── test_api_cases.py     # Focused API tests (4 test cases)
│       ├── test_users_api.py     # Comprehensive Users API tests
│       ├── test_posts_api.py     # Comprehensive Posts API tests
│       ├── test_comments_api.py  # Comprehensive Comments API tests
│       ├── conftest.py           # Pytest configuration
│       ├── utils.py              # API test utilities
│       └── schemas/              # JSON Schema files
│           ├── user_schema.json
│           ├── users_array_schema.json
│           ├── post_schema.json
│           ├── comment_schema.json
│           └── created_user_schema.json
├── 🛠️ Utilities
│   ├── stop_tests.py         # Stop running tests
│   ├── force_quit_browserstack.py  # Force quit BrowserStack sessions
│   ├── fix_browserstack_status.py  # Fix build status issues
│   ├── update_build_status.py     # Update BrowserStack build status
│   └── utils/                # Core utilities
│       ├── config.py         # Configuration settings
│       ├── helpers.py        # Helper functions
│       └── browserstack_helper.py  # BrowserStack integration
├── 🏗️ Core Directories
│   ├── pages/                # Page Object Model
│   │   ├── base_page.py      # Base page class
│   │   ├── login_page.py     # Login page object
│   │   ├── inventory_page.py # Inventory page object
│   │   └── cart_page.py      # Cart page object
│   └── reports/              # Generated test reports
│       ├── allure_results/   # Allure test results
│       ├── allure-report/    # Generated Allure reports
│       ├── pytest_html/      # Pytest HTML reports
│       ├── focused_api/      # Focused API test reports
│       └── screenshots/      # Test screenshots
├── ⚙️ Configuration
│   ├── browserstack.yml      # BrowserStack configuration
│   ├── browserstack.env      # BrowserStack environment variables
│   ├── env.example           # Environment variables template
│   ├── pytest.ini           # Pytest configuration
│   ├── requirements.txt      # Python dependencies
│   └── Makefile             # Build commands
├── 📚 Documentation
│   ├── TEST_EXECUTION_GUIDE.md      # Comprehensive execution guide
│   ├── EXECUTION_SUMMARY.md         # Quick reference summary
│   ├── BROWSERSTACK_CLEANUP_GUIDE.md # BrowserStack troubleshooting
│   └── README.md                    # This file
└── test_env/                 # Python virtual environment
    ├── bin/                  # Virtual environment binaries
    ├── lib/                  # Python packages
    └── pyvenv.cfg           # Virtual environment config

🛠️ Installation

Prerequisites

• Python 3.9 or higher
• pip (Python package installer)
• Git

Setup

1. Clone the repository

   git clone <repository-url>
   cd selenium-python-framework

2. Create a virtual environment

   python -m venv venv
   
   # On Windows
   venv\Scripts\activate
   
   # On macOS/Linux
   source venv/bin/activate

3. Install dependencies

   pip install -r requirements.txt

4. Install WebDriver The framework uses webdriver-manager to automatically manage WebDriver binaries.

BrowserStack Setup (Optional)

For cloud testing on BrowserStack:

1. Get BrowserStack credentials

   • Sign up at BrowserStack
   • Get your username and access key

2. Configure BrowserStack

   # Copy environment template
   cp env.example browserstack.env
   
   # Edit browserstack.env with your credentials
   nano browserstack.env

3. Set environment variables

   # Enable BrowserStack
   export BROWSERSTACK_ENABLED=true
   export BROWSERSTACK_USERNAME=your_username
   export BROWSERSTACK_ACCESS_KEY=your_access_key
   export BROWSERSTACK_PLATFORM_INDEX=0  # 0=Chrome, 1=Firefox, 2=Safari

🧪 Running Tests

Quick Start

Interactive Test Menu:

python quick_tests.py

Main Test Runner:

# UI tests (local)
python run_tests.py --type ui --env local

# UI tests (BrowserStack)
python run_tests.py --type ui --env browserstack

# API tests
python run_tests.py --type api

# All tests
python run_tests.py --type all

Test Execution Options

Environment Selection:

# Local testing (Chrome, Firefox, Safari)
python run_tests.py --type ui --env local --browser chrome
python run_tests.py --type ui --env local --browser firefox
python run_tests.py --type ui --env local --browser safari

# BrowserStack cloud testing
python run_tests.py --type ui --env browserstack --platform 0  # Chrome
python run_tests.py --type ui --env browserstack --platform 1  # Firefox

Test Type Selection:

# UI tests only (Behave BDD)
python run_tests.py --type ui --env local

# UI tests with Allure reporting
python run_tests.py --type ui --env local --allure

# API tests only (Pytest)
python run_tests.py --type api

# All tests (UI + API)
python run_tests.py --type all --env local

Feature Selection:

# Specific feature files
python run_tests.py --type ui --env local --feature features/login.feature
python run_tests.py --type ui --env local --feature features/cart.feature

# Multiple features
python run_tests.py --type ui --env local --feature features/login.feature features/cart.feature

Headless Mode:

# Run in headless mode (no browser window)
python run_tests.py --type ui --env local --headless

# Run with visible browser
python run_tests.py --type ui --env local --no-headless

Using Makefile Commands

Quick test execution:

# Run all UI tests
make test-ui

# Run focused API tests with HTML report
make test-focused-api-html

# Run all tests
make test-all

# Run tests with coverage
make test-complete

Complete BDD Test Suite

Run all BDD tests (UI + API):

python3 run_complete_tests.py --type bdd

Allure Reporting

UI Tests with Allure Reporting:

# Dedicated Allure runner
python3 run_ui_tests_allure.py

# Using main test runner
python3 run_tests.py --type ui --env local --allure

# Using Makefile
make test-ui-allure

Allure Report Management:

# Generate static Allure report
allure generate reports/allure_results/ --clean -o reports/allure-report

# Serve interactive Allure report (opens in browser)
allure serve reports/allure_results

# View static report
open reports/allure-report/index.html

Allure Report Features:

• Interactive Dashboard - Visual overview of test execution
• Step-by-Step Details - Detailed execution logs with screenshots
• Timeline View - Chronological test execution timeline
• Categories & Filtering - Filter tests by status, feature, or tags
• Screenshot Attachments - Visual debugging support
• Trend Analysis - Historical test execution trends

UI Tests (Behave BDD)

Run all UI tests:

# Using complete test runner
python3 run_complete_tests.py --type bdd

# Using Makefile
make test-ui

# Direct Behave command
behave features/login.feature features/cart.feature --no-capture

Run specific UI features:

# Login tests only
behave features/login.feature --no-capture

# Cart tests only
behave features/cart.feature --no-capture

Browser modes:

# Headless mode (no browser window)
HEADLESS=true behave features/login.feature features/cart.feature --no-capture
make test-ui  # Uses headless by default

# Headed mode (visible browser)
HEADLESS=false behave features/login.feature features/cart.feature --no-capture
make test-visible

# Specific browser
make test-chrome
make test-firefox

UI Test Coverage:

• ✅ TC_UI_01: Successful login with valid credentials
• ✅ TC_UI_02: Failed login with invalid password
• ✅ TC_UI_03: Add single item to cart & complete order
• ✅ TC_UI_04: Sort products by price low to high

API BDD Tests (Removed)

BDD API tests have been removed - API testing is now handled by Pytest for better maintainability and reporting.

API Tests (Focused + Comprehensive)

Run all API tests:

# Using complete test runner
python3 run_complete_tests.py --type api

# Using Makefile
make test-focused-api-html

# Direct focused API tests
python3 run_focused_api_html.py

Focused API Tests (4 Test Cases):

# With JSON report
python3 run_focused_api_tests.py
make test-focused-api

# With HTML report
python3 run_focused_api_html.py
make test-focused-api-html

Comprehensive API Tests (if pytest works):

# All API tests
python -m pytest api_tests/ -v --html=reports/pytest_html/pytest_api_report.html --self-contained-html

# Specific test modules
python -m pytest api_tests/test_users_api.py -v
python -m pytest api_tests/test_posts_api.py -v
python -m pytest api_tests/test_comments_api.py -v

# By markers
python -m pytest api_tests/ -m smoke -v
python -m pytest api_tests/ -m regression -v
python -m pytest api_tests/ -m api -v

API Test Coverage:

Focused API Tests (4 Test Cases):

• ✅ TC_API_01: Fetch user list - GET /api/users
• ✅ TC_API_02: Create a new user - POST /api/users
• ✅ TC_API_03: Valid login - POST /api/login
• ✅ TC_API_04: Missing password - POST /api/login

Comprehensive API Tests:

• ✅ Users API: GET, POST, PUT, PATCH, DELETE with JSON Schema validation
• ✅ Posts API: GET, POST, PUT, PATCH, DELETE with JSON Schema validation
• ✅ Comments API: GET, POST, PUT, PATCH, DELETE with JSON Schema validation
• ✅ Performance Testing: Response time validation
• ✅ Data Consistency: Multiple request validation
• ✅ Error Handling: Invalid data and edge cases

🚀 Quick Start Commands

Essential Commands

Run everything:

# Complete test suite (UI + API)
python3 run_complete_tests.py --type all

# Using Makefile
make test-all

UI Testing:

# All UI tests
make test-ui

# UI tests with visible browser
make test-visible

# Specific UI features
behave features/login.feature --no-capture
behave features/cart.feature --no-capture

API Testing:

# Focused API tests with HTML report
make test-focused-api-html

# Focused API tests with JSON report
make test-focused-api

# Direct execution
python3 run_focused_api_html.py

Reporting:

# Generate Allure reports
python3 run_with_allure.py

# View Allure reports
python3 view_allure_report.py

# Open HTML reports
open reports/pytest_html/focused_api_report.html

Complete Makefile Commands

Test Execution:

make test-ui              # Run UI tests (headless)
make test-ui-allure       # Run UI tests with Allure reporting
make test-visible         # Run UI tests (visible browser)
make test-focused-api     # Run focused API tests (JSON report)
make test-focused-api-html # Run focused API tests (HTML report)
make test-all            # Run all tests
make test-complete       # Run all tests with coverage

Browser-specific:

make test-chrome         # Run tests on Chrome
make test-firefox        # Run tests on Firefox
make test-headless       # Run tests in headless mode

Reporting:

make reports             # Generate all reports
make allure              # Generate Allure reports
make view-allure         # View Allure reports in browser

Setup:

make install             # Install dependencies
make setup               # Setup test environment
make help                # Show all available commands

Test Coverage

UI Test Cases:

• ✅ TC_UI_01: Successful login with valid credentials
• ✅ TC_UI_02: Failed login with invalid password
• ✅ TC_UI_03: Add single item to cart and complete order (E2E checkout flow)
• ✅ TC_UI_04: Sort products by price low to high

API Test Cases:

• ✅ TC_API_01: Fetch user list - GET /api/users
• ✅ TC_API_02: Create a new user - POST /api/users
• ✅ TC_API_03: Valid login - POST /api/login
• ✅ TC_API_04: Missing password - POST /api/login

Comprehensive API Tests:

• ✅ Users API: GET, POST, PUT, PATCH, DELETE with JSON Schema validation
• ✅ Posts API: GET, POST, PUT, PATCH, DELETE with JSON Schema validation
• ✅ Comments API: GET, POST, PUT, PATCH, DELETE with JSON Schema validation
• ✅ Performance Testing: Response time validation
• ✅ Data Consistency: Multiple request validation
• ✅ Error Handling: Invalid data and edge cases

📊 Test Reports

The framework generates comprehensive test reports:

Behave Reports

• Location: reports/behave/
• Text and JSON format reports
• Detailed step-by-step execution logs

Allure Reports

• Location: reports/allure-report/
• Interactive HTML reports with rich visualizations
• Test execution timeline and trends
• Screenshot attachments for each step
• Test case categorization and filtering

Framework Summary

• Location: reports/framework_summary.json
• Complete test execution summary
• Test case coverage and results

Screenshots

• Location: reports/screenshots/
• Test failure screenshots
• Visual debugging support
• Step-by-step execution screenshots

Generate Reports

python3 generate_reports.py

🎯 Allure Reporting Utilities

run_with_allure.py

A comprehensive test runner that executes all BDD tests and generates Allure reports automatically.

Features:

• Runs all BDD tests with Allure formatter
• Automatically generates Allure reports
• Handles test result file organization
• Provides detailed execution feedback
• Error handling and status reporting

Usage:

python3 run_with_allure.py

What it does:

1. Creates reports/allure_results/ directory
2. Runs all BDD tests with Allure formatter
3. Generates interactive Allure report
4. Provides report locations and viewing instructions

run_ui_tests_allure.py

A dedicated utility for running UI tests with Allure reporting.

Features:

• Runs all UI tests with Allure formatter
• Automatically generates Allure reports
• Handles test result file organization
• Provides detailed execution feedback
• Error handling and status reporting
• Interactive report serving option

Usage:

# Run UI tests with Allure reporting
python3 run_ui_tests_allure.py

# Serve interactive report
python3 run_ui_tests_allure.py --serve

What it does:

1. Creates reports/allure_results/ directory
2. Runs UI tests with Allure formatter
3. Generates static Allure report
4. Provides report locations and viewing instructions
5. Optionally serves interactive report

view_allure_report.py

A convenient utility to open Allure reports in your default browser.

Features:

• Automatically starts Allure server
• Opens report in default browser
• Handles server lifecycle management
• Validates test result files before serving
• Graceful shutdown with Ctrl+C

Usage:

python3 view_allure_report.py

What it does:

1. Checks for existing test results
2. Starts Allure serve process
3. Opens report in browser automatically
4. Keeps server running until stopped

Allure Report Features

• Interactive Dashboard: Visual overview of test execution
• Test Case Details: Step-by-step execution with screenshots
• Timeline View: Chronological test execution timeline
• Categories: Test categorization (passed, failed, skipped)
• Trends: Historical test execution trends
• Attachments: Screenshots and logs for each step
• Filtering: Filter tests by status, feature, or tags

🔧 Configuration

Behave Configuration

Edit features/behave.ini to modify BDD test settings:

[behave]
paths = features
default_format = pretty
environment_file = env.py

Environment Variables

Set environment variables for test execution:

# Browser mode
HEADLESS=true    # Run in headless mode
HEADLESS=false   # Run in headed mode (visible browser)

# API base URL
API_BASE_URL=https://jsonplaceholder.typicode.com

Page Object Configuration

Edit pages/ classes to modify element locators and page interactions.

🏷️ BDD Test Structure

The framework uses Gherkin syntax for test scenarios:

Feature Files

• login.feature - UI login scenarios
• cart.feature - UI cart and inventory scenarios
• api_login.feature - API login scenarios
• api_users.feature - API user management scenarios

Step Definitions

• login_steps.py - UI login step implementations
• cart_steps.py - UI cart step implementations
• api_steps.py - API step implementations

Test Scenarios

Each feature file contains multiple scenarios covering:

• Happy path testing
• Error handling
• Edge cases
• Data validation

🚀 CI/CD Integration

Local Test Execution

# Run complete BDD test suite
python3 run_complete_tests.py --type bdd

# Run with Allure reporting
python3 run_with_allure.py

# View Allure report in browser
python3 view_allure_report.py

# Run with specific browser mode
HEADLESS=true python3 run_complete_tests.py --type bdd

# Generate comprehensive reports
python3 generate_reports.py

Continuous Integration

The framework is designed to integrate with CI/CD systems:

• GitHub Actions
• Jenkins
• GitLab CI
• Azure DevOps

Test Execution Modes

• Headed Mode: Visible browser for debugging
• Headless Mode: Background execution for CI/CD
• API Testing: Real HTTP endpoint testing
• UI Testing: Selenium WebDriver automation

📝 Writing BDD Tests

Creating Feature Files

Create new .feature files in the features/ directory:

Feature: New Feature
  As a user
  I want to perform some action
  So that I can achieve a goal

  Scenario: Test scenario
    Given some precondition
    When I perform an action
    Then I should see expected result

Step Definitions

Create step definitions in features/steps/:

from behave import given, when, then

@given('some precondition')
def step_precondition(context):
    # Implementation here
    pass

@when('I perform an action')
def step_action(context):
    # Implementation here
    pass

@then('I should see expected result')
def step_verification(context):
    # Assertions here
    pass

Page Object Model

Extend BasePage for new page objects:

from pages.base_page import BasePage

class MyPage(BasePage):
    # Locators
    ELEMENT_LOCATOR = (By.ID, "element-id")
    
    def __init__(self, driver):
        super().__init__(driver)
    
    def perform_action(self):
        self.click_element(self.ELEMENT_LOCATOR)

Example BDD Scenario

Feature: User Login
  Scenario: Successful login
    Given the user is on the login page
    When the user enters username "standard_user"
    And the user enters password "secret_sauce"
    And the user clicks the login button
    Then the user should be redirected to the inventory page

🐛 Debugging

Run in Headed Mode

# Run with visible browser for debugging
HEADLESS=false behave features/login.feature --no-capture

Enable Debug Logging

import logging
logging.basicConfig(level=logging.DEBUG)

Take Screenshots

Screenshots are automatically saved to reports/screenshots/ on test failures.

Step-by-Step Debugging

Add print statements in step definitions:

@when('I perform an action')
def step_action(context):
    print("🔍 Debug: Performing action...")
    # Implementation here
    print("✅ Debug: Action completed")

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Run the test suite
6. Submit a pull request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

For questions and support:

1. Check the documentation
2. Search existing issues
3. Create a new issue with detailed information
4. Contact the maintainers

🌐 BrowserStack Integration

BrowserStack Utilities

Session Management:

# List running BrowserStack sessions
python force_quit_browserstack.py --list

# Force quit all running sessions
python force_quit_browserstack.py --quit

# Fix build status issues
python fix_browserstack_status.py

# Update build status
python update_build_status.py --update

Session URLs and Build Names:

• Every BrowserStack execution displays session URLs
• Unique build names with timestamps
• Real-time session monitoring
• Automatic cleanup after test completion

Supported Platforms:

• Platform 0: Chrome (Latest)
• Platform 1: Firefox (Latest)
• Platform 2: Safari (Latest)

BrowserStack Configuration

browserstack.yml:

platforms:
  - browserName: Chrome
    browserVersion: latest
    os: OS X
    osVersion: Sonoma
  - browserName: Firefox
    browserVersion: latest
    os: OS X
    osVersion: Sonoma
  - browserName: Safari
    browserVersion: latest
    os: OS X
    osVersion: Sonoma

Environment Variables:

BROWSERSTACK_ENABLED=true
BROWSERSTACK_USERNAME=your_username
BROWSERSTACK_ACCESS_KEY=your_access_key
BROWSERSTACK_PLATFORM_INDEX=0

🔄 Version History

• v1.0.0 - Initial release with basic framework
• v1.1.0 - Added BDD support and API testing
• v1.2.0 - Enhanced reporting and CI/CD integration
• v2.0.0 - Complete BDD framework with cleaned structure
• v2.1.0 - BrowserStack cloud testing integration
  • Added BrowserStack support for cloud testing
  • Interactive test execution menu
  • Enhanced test runner with environment selection
  • Browser and platform selection options
  • Session management utilities
  • Build status monitoring
  • Comprehensive cleanup tools
  • Updated project structure and documentation

🆕 Recent Updates

Allure Reporting Integration

• New Allure Runner: run_ui_tests_allure.py for dedicated Allure reporting
• Enhanced Test Runner: Added --allure flag to run_tests.py
• Makefile Integration: make test-ui-allure command
• Rich Visual Reports: Interactive dashboards with screenshots and timelines

Enhanced Test Coverage

• Updated TC_UI_03: Now includes complete E2E checkout flow
• Focused API Tests: Streamlined to 4 essential test cases
• Security Updates: Updated black formatter to resolve CVE-2024-21503

Improved Documentation

• Comprehensive README: Updated with all new features and commands
• Clear Examples: Step-by-step instructions for all functionality
• Multiple Execution Options: Local, BrowserStack, and Allure reporting

---

Happy Testing! 🎉